home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / mint / mint96sb.zoo / doc / shm.doc < prev    next >
Text File  |  1992-10-07  |  4KB  |  93 lines
  1. Shared Memory and How To Use It
  2.  
  3. MiNT has a special directory, U:\SHM, which provides a place for
  4. programs to advertise memory that they are offering to share.
  5. To create a shared memory file, a program uses the Fcreate call
  6. to create a file in U:\SHM, e.g.:
  7.  
  8. fd = Fcreate("U:\\SHM\\MY.SHARE", 0);
  9.  
  10. It then uses an Fcntl call to attach a block of memory (previously
  11. allocated by Malloc or Mxalloc) to the file:
  12.  
  13. blk = Malloc(128L);
  14. Fcntl(fd, blk, SHMSETBLK);
  15.  
  16.  
  17. Several things should be noted when creating a shared memory
  18. file:
  19.  
  20. (1) The file's attributes must be 0. Read-only shared memory, or
  21. shared memory with other attributes, is not yet implemented,
  22. but may be in the future.
  23.  
  24. (2) Two shared memory files cannot have the same name. An attempt
  25. to create a new shared memory file with the same name as an
  26. existing one will fail with an access denied error (EACCDN).
  27.  
  28. (3) Once the block of memory has been attached to the file, it
  29. may be accessed by any application that opens the file.
  30.  
  31. (4) A shared memory file (and associated block) remain allocated
  32. even after the program which created it terminates. It can be
  33. deleted (and the associated memory freed) with an Fdelete()
  34. system call.
  35.  
  36. (5) The size of the shared memory file will be the actual size
  37. of the memory block. This may be somewhat larger than the
  38. size requested in the Malloc or Mxalloc request, due to memory
  39. rounding.
  40.  
  41.  
  42. To use a shared memory block, a client application must open
  43. the file and use the SHMGETBLK Fcntl to gain access to it.
  44. For example:
  45.  
  46. fd = Fopen("U:\\SHM\\MY.SHARE", 2);
  47. blk = Fcntl(fd, 0L, SHMGETBLK);
  48. Fclose(fd); /* optional -- see below */
  49.  
  50. Things to note:
  51.  
  52. (1) The address of the shared memory block is returned by the
  53. Fcntl call. NOTE THAT THIS ADDRESS MAY BE DIFFERENT FOR
  54. DIFFERENT PROGRAMS. That is, a shared memory block that appears
  55. at address 0x01000100 in one program may appear at address
  56. 0x0007f000 in another. In particular, shared memory blocks
  57. should not contain absolute addresses (e.g. pointers).
  58.  
  59. (2) The extra argument passed to Fcntl is reserved for future
  60. expansion; use 0L for now to ensure compatibility with
  61. future versions of MiNT.
  62.  
  63. (3) The mode argument in the Fopen function must be an accurate
  64. reflection of how the program plans to use the memory; read and
  65. write access permissions will be enforced in future versions
  66. of MiNT.
  67.  
  68. (4) If no SHMSETBLK has been made for the file, a SHMGETBLK Fcntl
  69. will return a NULL pointer to indicate an error.
  70.  
  71. (5) If a program is finished with a shared memory block and no
  72. longer wishes to use it, it should call Mfree() with the address
  73. of the block (i.e. the address returned by Fcntl(fd, 0L, SHMGETBLK)).
  74.  
  75.  
  76. Deleting a Shared Memory File
  77.  
  78. The Fdelete() system call may be used to delete a shared memory
  79. file. This will *not* necessarily free the associated memory;
  80. the memory will actually be freed only after (1) the file has
  81. been deleted, and (2) all processes using the memory have
  82. freed the memory, either directly or as a result of the process
  83. terminating.
  84.  
  85. Fdelete() will fail if the shared memory file is still open.
  86. Processes may omit the Fclose() call if they wish this to happen;
  87. it's a way of informing the process trying to delete the file
  88. that people are still interested in it. Note that it is *not*
  89. harmful to allow the Fdelete to occur, since (as noted above)
  90. the memory will not actually be freed until everyone is finished
  91. with it; but sometimes it may be useful for programs to know that
  92. the memory is still in use.
  93.